docs: add Agent Skills SKILL.md#1949
docs: add Agent Skills SKILL.md#1949bearomorphism wants to merge 1 commit intocommitizen-tools:masterfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a root-level SKILL.md documenting Commitizen usage for agentic workflows (command selection, config discovery, bump/changelog safety, CI considerations) in the Agent Skills format.
Changes:
- Introduces
SKILL.mdwith YAML frontmatter (name,description, etc.) and Commitizen-oriented guidance. - Documents config discovery order, safe/read-only command patterns, and bump/changelog operational cautions.
- Adds curated links to existing command/config/CI/exit-code documentation plus a few CLI examples.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
bearomorphism
force-pushed
the
docs/add-skill-md
branch
from
db35496 to
944797a
Compare
ValidationVerified that all review comments have been addressed:
Currently researching whether SKILL.md at the repo root follows the intended Agent Skills discovery pattern. Will update with findings. |
Research Findings on Agent Skills DiscoveryAfter researching the Agent Skills spec and how agents actually discover skills: SKILL.md at the repo root will NOT be auto-discovered by any agent. The spec requires skills to live in a named subdirectory within a skills folder:
35 agents support this format (Claude Code, VS Code/Copilot, Cursor, Gemini CLI, OpenAI Codex, etc.), but they all scan these specific directories — not the repo root. Recommendation: Move \SKILL.md\ to .agents/skills/commitizen/SKILL.md\ so agents working within this repo can discover it automatically. This also satisfies the spec constraint that the directory name must match the Note: No other major Python CLI tool (ruff, black, pytest, pre-commit) has adopted SKILL.md yet — commitizen would be an early adopter. |
Add SKILL.md at .agents/skills/commitizen/ following the Agent Skills spec so that AI agents working in this repo can auto-discover it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bearomorphism
force-pushed
the
docs/add-skill-md
branch
from
944797a to
ca1e776
Compare
Description
Add a SKILL.md following the Agent Skills spec at
.agents/skills/commitizen/SKILL.md, so AI agents working in this repo can auto-discover Commitizen's capabilities.The file provides concise guidance on command selection, configuration discovery, versioning, changelog generation, CI workflows, and exit-code handling.
Checklist
Was generative AI tooling used to co-author this PR?
Generated-by: GitHub Copilot CLI following the guidelines
Code Changes
uv run poe alllocally to ensure this change passes linter check and testsDocumentation Changes
uv run poe doclocally to ensure the documentation pages renders correctlyExpected Behavior
Agents supporting the Agent Skills format (Claude Code, VS Code/Copilot, Cursor, Gemini CLI, OpenAI Codex, etc.) can auto-discover the skill at
.agents/skills/commitizen/SKILL.mdwhen working in this repo.Steps to Test This Pull Request
.agents/skills/commitizen/SKILL.mdexistsnameanddescriptionfieldscommitizen) matches thenamefield in frontmatterAdditional Context
Part of #1936. The llms.txt portion is addressed in PR #1948.
Moved from repo root to
.agents/skills/commitizen/based on research showing that compliant agents scan.agents/skills/<name>/directories, not the repo root. See PR comment for full research findings.